.\"  -*- nroff -*-
.\" 
.\" twilio-utils - Command line utilities for Twilio users
.\" 
.\" Copyright 2013 Archie L. Cobbs <archie@dellroad.org>
.\" 
.\" Licensed under the Apache License, Version 2.0 (the "License"); you may
.\" not use this file except in compliance with the License. You may obtain
.\" a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
.\" 
.\" Unless required by applicable law or agreed to in writing, software
.\" distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
.\" WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
.\" License for the specific language governing permissions and limitations
.\" under the License.
.\"
.\" $Id: twiping.1.in 37 2014-12-09 14:42:07Z archie.cobbs $
.\"
.Dd Dec 8, 2014
.Dt TWIPING 1
.Os
.Sh NAME
.Nm twiping
.Nd Send SMS ping via the Twilio REST API
.Sh SYNOPSIS
.Nm twiping
.Bk -words
.Op Fl c Ar file
.Op Fl C Ar flag
.Op Fl F Ar number
.Op Fl t Ar testcode
.Op Fl w Ar timeout
.Ar number
.Ek
.Sh DESCRIPTION
.Nm
attempts to transmit a single outoing SMS message containing a unique test code
to the specified
.Ar number ,
and then waits for an SMS response containing the same test code, using the Twilio REST API.
.Pp
The test message has the form
.Ar TESTxxxxxxxx
where the `x' characters are replaced by random hex digits.
.Pp
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl c
Specify the configuration file.
.Pp
This file is simply a shell script that when sourced must define the
.Pa ACCOUNT_SID
and
.Pa AUTH_TOKEN
shell variables containing the corresponding Twilio credentials.
This file must also define
.Pa FROM_NUMBER
shell variable if the
.Fl F
flag is not used to specify the sending SMS phone number.
.Pp
If the
.Fl c
flag is not specified,
.Pa @defaultconf@
is assumed.
.It Fl C
Pass
.Ar flag
to
.Xr curl 1 .
.It Fl F
Specify the sending SMS phone number.
This flag is required if the configuration file does not define a default
.Pa FROM_NUMBER .
.It Fl t
Don't generate or send a test code.
Instead, assume the specified
.Ar testcode
has just been sent and expect a reply normally.
.It Fl w
Wait up to
.Ar timeout
seconds for a reply.
The default timeout is 30 seconds.
.El
.Sh EXIT STATUS
.Nm
exits zero normally, 1 an error occurs, or 2 if no reponse is received within the specified timeout.
.Pp
Errors returned from the Twilio REST API are reported to standard error.
.Sh SEE ALSO
.Xr curl 1 ,
.Xr smslen 1 ,
.Xr twimsg 1 ,
.Xr twilog 1 .
.Sh AUTHOR
.An Archie L. Cobbs Aq archie@dellroad.org
